Operator Library: Hardware Platform
This operator represents the image data interface between a CXP camera and VisualApplets. The operator can be used for single channel, dual channel or quad channel CXP interfaces. The type of interface is selected by the parameter ConnectionCount. The operator outputs raw image data no matter what format the camera delivers. You then need to convert this image data into the format sent by the camera. To convert the image data, use appropriate operators for aggregating and casting raw byte values to pixel values . Certain situations during operation may be communicated via the event system as described below. Additionally, the operator has various parameters signalling the status of the connection to the camera.
If the operator detects that a frame is larger or smaller than what was promoted by the camera in the CXP image header, a safety circuit gets activated. The operator will then cut off exceeding pixels and lines, so that VisualApplets sees always the frame size which was defined in the image header. If the frame is smaller in its dimensions than what was specified in the image header, the operator will fill up the received frame with undefined data to achieve the specified frame dimensions which were defined in the image header. Filling up a smaller frame can cause the following frames to get lost. The loss will be reported per event to the software, also the size mismatch will cause an event, too.
| Available for Hardware Platforms |
|---|
| imaFlex CXP-12 Quad |
Instantiation in VisualApplets
The operator provides image data on its output O. This output is always present. In addition to this standard output port, you can configure an optional MetaDataO output for the CXP header meta-data. The following pop-up dialog appears during operator instantiation:
Here, you can specify the optional meta data port. If you set the port availability to "0" (default), the port will not be present in the operator. If you set the port availability to 1, the meta data port is available in the operator interface.
Optional MetaDataO Port
The format for the 32-bit output is shown in the following picture.
Each CXP frame provides a corresponding error-free image header. For incorrect image header, no image stream data is sourced into the VisualApplets pipeline. The compressed image header consist of 6 words. The last byte is used for additional information, which is for internal usage only. Particularly, the HeaderError bit informs if the image header itself got an error or not.
| Imageeader | Description |
|---|---|
| StreamId | ID of the CXP stream |
| Tag | 16-bit source image index. It is incremented for each transferred image, wraps around to 0 at 0xFFFF. The same number shall be used by each stream containing data relating to the same image (in case of multi-tap streams). |
| XSize | 24-bit value representing the image width in pixels. |
| XOff | 24-bit value representing the horizontal offset in pixels of the image with respect to the left hand pixel of the full device image. |
| YSize | 24-bit value representing the image height in pixels. This value is set to 0 for line scan images. |
| YOff | 24-bit value representing the vertical offset in pixels of the image with respect to the top line of the full device image. This value is set to 0 for line scan images. |
| DSizeL | 24-bit value representing the number of data words per image line. |
| PixelF | 16-bit value representing the pixel format. |
| TapG | 16 bit value representing the tap geometry. |
| Flags | Image flags. |
| x-Mirror | (Not used yet). Describes whether the incoming image is x-mirrored or not. |
| y-Mirror | (Not used yet). Describes whether the incoming image is y-mirrored or not. |
| HeaderError |
1: Image header has an error and the frame is declared as lost. There is no corresponding image data exists in the operator output data stream. 0: Image header is correct and there is a corresponding image data exists in the operator output data stream. |
Device Resource Usage
The operator uses one or more resources of type CameraPort depending on the selection of the parameter ConnectionCount. For the event system a resource of the type EventPort is used. If ConnectionCount is set to X4 (quad channel), the following resource dialog opens up:
![[Important]](../common/images/admon/important.png) |
Modifying Image Width and Image Height |
|---|---|
|
Via the maximum image width and height properties of the output link you can adjust width and height to the camera-specific settings. However, the maximum image width on operator port O must be divisible by the parallelism of port O. Thus, make sure the maximum image width is divisible by the parallelism of port O! |
Error Handling and Event System
When the operator detects that the received reconstructed frame is larger or smaller than what was promoted by the camera in the CXP image header, a safety circuit gets activated. The operator then cuts off exceeding pixels and lines, so that the subsequent processing pipeline always sees the frame size which was defined in the image header. If the received frame is smaller in its dimensions than what was specified in the image header, the operator fills up the received frame with undefined data to achieve the specified frame dimensions which were defined in the image header. Filling up of a smaller frame can cause the follow-up frames to get lost. The loss is then reported per event to the software (see the following paragraph). The size mismatch causes an event, too.
For a set of very critical errors, the operator will forward asynchronous events to the host runtime software (Framegrabber SDK). The event name in the Framegrabber API is <hierarchical operator name>\CxpStreamStatus, e.g. Device1\Process0\Camera\CxpStreamStatus. The event payload is provided as four 16-bit data words. The event format is defined as follows:
-
word [0]:
-
bits [0:15]: CXP image tag in which the event occurred.
-
-
word [1]:
-
bits [8:15]: Stream ID in which the event occurred.
-
bits [0:7]: reserved, treat as don't care.
-
-
word [2]:
-
bit [0]: CRC error occurred.
-
bit [1]: Stream marker error detected in the image header.
-
bit [2]: An error in the image header was detected which could not be corrected.
-
bit [3]: A frame size error was detected, i.e. the image size defined in the CXP image header is not matching the reconstructed frame size from the transmitted packets. This happens when the camera puts one info into the image header but transmits different amount of data as promoted in the header.
-
bits [4:15]: reserved, treat as don't care.
-
-
word [3]:
-
bit [0]: Event type, 0 = Corrupted Entity, 1 = Lost Entity.
-
Corrupted Entity means that the error happens within a frame and that frame is already sourced into the VisualApplets pipeline.
-
Lost Entity means that the error occurred before the frame was forwarded to the following operators and the frame was discarded by the camera operator.
-
When a corrupted entity is observed, the operator will fill up the frame according to the CXP image header definition so the following operators will not cause undefined behavior. During this fill-up, a new frame may arrive and will then get lost. The lost entity event will also be raised when the camera sends data with a gap according to the frame tag.
-
-
bit [1]: Event loss for type Corrupted Entity occurred. This means that preceding events of type Corrupted Entity got lost. This happens when the runtime software is not reacting to events and the internal event queues ran full.
-
bit [2]: Event loss for type Lost Entity occurred. This means that preceding events of type Lost Entity got lost. This happens when the runtime software is not reacting to events and the internal event queues ran full.
-
bits [3:15]: Amount of lost Lost Entity events.
-
There are two types of events: events for corrupted entities and events for lost entities. Bit 0 of word 3 describes which kind of event occurred. If the event buffers are full, it might happen that events get lost. When an event gets lost that marks a corrupted entity, bit 1 of word 3 will be set. When an event gets lost that marks a lost entity, bit 2 of word 3 will be set and bit 3 to 15 will provide the number of lost events indicating a lost frame. If bit 2 is set but the counter is 0, it means that a counter overflow happened.
Every event causes a software interrupt. To reduce the number of events, several events with the same frame tag might be merged together. In that case some error flags are combined. If an event was lost, the event before the lost event contains the information about the lost event and cannot be merged with further events with the same frame tag.
The events caused due to CRC errors report a frame tag, which may not be exactly related to the frame in which the CRC errors happens. The frame tag can be that of the preceding or following frame. This can only happen, when a camera sends a CXP packet, which contains a transition between 2 or more frames. The CRC computation is finished at the end of the packet, but the stream data is reconstructed on-the-fly. This means that a situation can happen, when a CRC error is detected after the preceding frame was already sent by the operator. In normal situations, where the camera packets don't contain data both of the end of the ongoing frame and the beginning of the next frame, the frame tag during CRC error will always be correct. For all other cases as long as the complete frame stream data is less than the maximal packet size of 8k, there might be only 1 frame overlap within 1 packet. In that case the software application should consider the preceding frame with the frame tag - 1 and the following frame with the frame tag + 1 as potentially corrupted as well.
| Property | Value |
|---|---|
| Operator Type | M |
| Output Links | O, image data output MetaDataO, optional meta data output |
| Link Parameter | Output Link O | Output Link MetaDataO |
|---|---|---|
| Bit Width | 32 | |
| Arithmetic | unsigned | unsigned |
| Parallelism | auto | 1 |
| Kernel Columns | 1 | 1 |
| Kernel Rows | 1 | 1 |
| Img Protocol | {VALT_IMAGE2D, VALT_LINE1D} (default: VALT_IMAGE2D) | {VALT_IMAGE2D, VALT_LINE1D, VALT_PIXEL0D} (default: VALT_IMAGE2D) |
| Color Format | VAF_GRAY | VAF_GRAY |
| Color Flavor | FL_NONE | FL_NONE |
| Max. Img Width | any (default: 1032) | 6 |
| Max. Img Height | any (default: 1032) | 1 |
| ConnectionCount | |
|---|---|
| Type | Static Write parameter |
| Default | X1 |
| Range | {X1, X2, X4} |
|
The parameter ConnectionCount defines the number of CXP lanes aggregated to the CXP link. The indices of the used connection ports are handled by resources of the type CameraPort. The number of port resources matches the connection count (e.g. X2: two CameraPort resource items). When you instantiate more than one CxpCamera operator (e.g. for dual-camera applet), resource conflicts may occur when multiple resources with the same index are used or when the number of consumed CameraPort resources exceeds the maximum of 4. In this case, the design rules check reports an error. |
|
| ResetStatus | |
|---|---|
| Type | Dynamic Write parameter |
| Default | Off |
| Range | {Off, On} |
|
The parameter ResetStatus resets the camera statistics, i.e. the error counters. |
|
| UsedConnections | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | {1,2,4} |
|
The parameter UsedConnections shows the amount of CXP lanes configured by the discovery software at runtime. |
|
| PacketTagErrorCount | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | [0 : 8191] |
|
The parameter PacketTagErrorCount shows how many received packets have a tag that is non-compliant with the expected tag according to the CXP standard. In particular this value is counting up when gaps are observed in following stream packet tag enumerations. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care. |
|
| ImageTagErrorCount | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | [0 : 8191] |
|
The parameter counts how many mismatches occur between the image header tag, the expected tag according to the CXP standard and the received tag. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care. |
|
| StreamIdErrorCount | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | [0 : 8191] |
|
The parameter counts how often the received stream-ID value in the stream packets mismatches the stream-ID value specified in the image header. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care. |
|
| CorrectedErrorCount | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | [0 : 8191] |
|
The parameter counts how many detected errors in the image header or the line markers have been corrected. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care. |
|
| UncorrectedErrorCount | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | [0 : 8191] |
|
The parameter counts how many detected errors in the image header or the line markers could not be corrected due to multiple bit errors in same byte. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care. |
|
| PacketBufferOverflowCount | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | [0 : 8191] |
|
The parameter counts how often the packet buffer overflow occurs in the channel bonding in aggregated mode. This parameter is only relevant for ConnectionCount = X2 or X4. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care. |
|
| PacketBufferOverflowSource | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | [0x0 : 0xf] |
|
The parameter implements a bit mask to query in which of the potential 4 CXP channels the packet buffer overflow occurred. The parameter width depends on the parameter ConnectionCount. In X1 mode, the parameter width is 1 bit wide, in X2 mode, the parameter width is 2 bit wide and in X4 mode the parameter width is 4 bit wide. The order is: LSB = lowest CXP channel number, MSB = highest CXP channel number allocated by the operator. |
|
| CameraScanMode | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | {area,line} |
|
The received image header carries the information whether the stream is for the area scan or for the line scan applications. This parameter shows the last valid received stream image header information. |
|
| MarkerErrorCount | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | [0 : 8191] |
|
The parameter counts how often the sequence of the CXP stream marker and the header or the line markers was incorrect. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care. |
|
| UnexpectedStartupData | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | {false, true} |
|
The parameter detects the error situation in which the first data value after the operator reset was unexpected, i.e. no image header is received before. This situation can happen due to a buggy implementation of the camera, frame grabber firmware or wrong software control of the discovery procedure. Also, a hardware defect of the camera could theoretically cause such a situation. |
|
| FrameLostCount | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | [0 : 33554431] |
|
The parameter counts the frames that were lost during acquisition and are not sent into the VisualApplets pipeline. Frames are lost when an error in the image header is detected or when a frame overlaps with another frame. The parameter is 25 bit wide where the bits [23:0] represent the actual counter value and the bit [24] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care. |
|
| FrameCorruptedCount | |
|---|---|
| Type | Dynamic Read parameter |
| Default | |
| Range | [0 : 33554431] |
|
The parameter counts the corrupted frames during acquisition. Corrupted frames are frames with error pixels which are sent to the VisualApplets pipeline. The parameter is 25 bit wide where the bits [23:0] represent the actual counter value and the bit [24] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care. |
|
The use of operator CxpCamera is shown in the following examples:
-
Tutorial - Basic Acquisition
-
Tutorial - Basic Acquisition
-
'Area Scan Trigger for imaFlex CXP-12 Quad'
An area scan trigger for CoaXPress12 is presented. External sources, an internal frequency generator or software trigger pulses can be used for trigger generation.
-
'Line Scan Trigger for imaFlex CXP-12 Quad Using Signal Operators'
A line scan trigger for CoaXPress12 is presented. The trigger includes an image trigger using a capture gate as well as a multi functional line trigger. External sources, an internal frequency generator or software trigger pulses can be used for trigger generation.
Prev
